home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_8 / issue_06 / risc_os / Wimp / Misc < prev    next >
Encoding:
Text File  |  1988-12-06  |  10.1 KB  |  251 lines
  1. > Wimp.Misc
  2.  
  3. New Calls
  4. ---------
  5.  
  6.         Wimp_BlockCopy
  7.         Wimp_GetWindowOutline
  8.         Wimp_PollIdle
  9.         Wimp_CommandWindow
  10.         Wimp_ReadSysInfo
  11.  
  12.         window flags bit 10 ==> don't use colour translation table
  13.         window flags bit 11 ==> don't open any other windows below this one
  14.         window flags bit 12 ==> grab 'hot keys' (see Wimp.Text)
  15.         window areaCBptr =1 ==> use common sprite area
  16.         window bounds           changed to cover whole screen
  17.                                 window min x,y can be supplied
  18.         Service_MouseTrap       provided for mouse-exec utilities
  19.  
  20.  
  21. Bug fixes
  22. ---------
  23.  
  24. Wimp_GetPointerInfo     bug fixed (oldbuttons not returned now)
  25. Entry:  R1 --> block
  26. Exit:   block updated
  27.           +0  mouse x coordinate
  28.           +4  mouse y coordinate
  29.           +8  button state
  30.          +12  window handle
  31.          +16  icon handle
  32.  
  33. On Arthur 1.20, this call used to return an extra word in [R1+20], which was
  34. not documented.  It now doesn't return it.
  35.  
  36.  
  37. Wimp_BlockCopy
  38. --------------
  39.  
  40. Entry:  R0 = window handle
  41.         R1-R4 = source rectangle (x0,y0,x1,y1 in window coordinates)
  42.         R5,R6 = bottom-left of destination (in window coordinates)
  43.  
  44. This call can be used to copy an area of a window's work area to another
  45. position within the window.  It will block-copy as much of the rectangle as
  46. it can, and will mark invalid any parts of the destination rectangle which
  47. could not be copied from the source (because it was not visible).
  48.  
  49. This call allows text editors, for example, to optimise the repainting of
  50. their data when inserting or deleting lines of text.  It copes with the
  51. problems involved with dealing with multiple visible rectangles.
  52.  
  53.  
  54. Wimp_GetWindowOutline
  55. ---------------------
  56.  
  57. Entry:  R1 --> block:
  58.           +0  window handle
  59. Exit:   block updated
  60.           +0  window handle
  61.           +4  x0,y0,x1,y1 (bounding box of window outline on screen)
  62.  
  63. This call should be used if, for example, a program wishes to confine the
  64. mouse pointer to the rectangle covering the window (including the borders).
  65.  
  66.  
  67. Wimp_PollIdle
  68. -------------
  69.  
  70. Entry:  R0 = flags (as for Wimp_Poll)
  71.         R1 --> block (as for Wimp_Poll)
  72.         R2 = earliest time for null return
  73. Exit:   as for Wimp_Poll
  74.  
  75. This call is useful for programs which maintain an animated display of some
  76. sort (eg. a clock), allowing them to wait for a specified amount of time
  77. without chewing up CPU time.
  78.  
  79. The time specified in R2 relates to the values returned by
  80. OS_ReadMonotonicTime, which the Wimp calls to work out when the time limit is
  81. up.  When a null event is received, the application should perform its normal
  82. graphical output, then add the appropriate amount of time to the time it
  83. previously passed to Wimp_PollIdle (rather than adding on to the current
  84. time).  In this way the problem of time 'slipping' is avoided.
  85.  
  86. One problem with this approach, however, is that if some program decides to
  87. 'hog' the CPU for several seconds, then a clock can find itself several
  88. seconds behind.  When called again, instead of immediately catching up, it
  89. may end up being called continuously for a while until its internal time
  90. catches up with the actual time.  To get round this problem, it is
  91. recommended that programs such as clocks move forward in whole seconds from
  92. their previous time until the new time is greater than the current time.
  93.  
  94.  
  95. Wimp_CommandWindow
  96. ------------------
  97.  
  98. Entry:  R0 --> message to put in window title
  99.                mark command window pending: if any chars printed, open it
  100.         R0 = 1 ==> treat command window as open, without setting text window
  101.         R0 = 0 ==> close command window, prompting if anything was printed
  102.         R0 =-1 ==> close command window, without any fuss
  103.  
  104. This facility has been provided to deal with those awkward situations where
  105. old-style text-based programs need to be run, which rely on the screen being
  106. organised like a teletype (ie. they run in 'VDU 4' mode).
  107.  
  108. When Wimp_CommandWindow is called with R0>0, the Wimp marks the command
  109. window as 'pending', and intercepts WrchV.  When the first character is sent
  110. to the screen, the command window is displayed and a text window opened
  111. within it.  The command also causes the setting of the escape enabled bit,
  112. the soft keys and cursor keys to be set to their normal values outside the
  113. Wimp.  When the command window is closed, these values are restored.
  114.  
  115. This facility is used by the Wimp itself when starting tasks, since it is not
  116. possible to determine in advance whether a task will use the Wimp for its
  117. output, or will simply send 'printable' characters to the screen.  If the
  118. task calls Wimp_Initialise, the command window is closed and never appears on
  119. the screen, but if characters are sent to the screen, the window is opened to
  120. receive them.
  121.  
  122. Note that the Wimp_ReportError command takes note of whether a command window
  123. is pending or active:  if the window is active, the error is reported within
  124. the text window, but if the window is dormant or merely pending, it is marked
  125. as 'suspended' for the duration of the error report, and the error is
  126. reported in a window.  Note that UpCalls to deal with disc swapping use
  127. Wimp_ReportError, and so benefit from this code (see Wimp.Errors for further
  128. details).  For this reason the ShellCLI module calls Wimp_CommandWindow with
  129. R0 = 1, so that the Wimp treats the command window as being open, and reports
  130. errors as lines of text (rather than in the error window).
  131.  
  132. The Filer and ADFS Filer also use the Wimp_CommandWindow facility, when
  133. invoking old-fashioned commands such as *Copy and *Backup.  The command is
  134. especially useful for *Copy, since depending on the user's setting of the
  135. Copy$Options variable, the command may or may not result in output being sent
  136. to the screen.
  137.  
  138.  
  139. Wimp_ReadSysInfo
  140. ----------------
  141.  
  142. Entry:  R0 = index
  143.              0 ==> read number of active tasks
  144.              all other values are reserved
  145. Exit:   R0 = value (depends on R0 on entry)
  146.  
  147. This call is provided to cover all those niggling little things that do not
  148. fit nicely anywhere else.
  149.  
  150. Currently the only value that is returned by this call is the number of
  151. active tasks.  This value may be used by an application to determine whether
  152. or not it is running in the Wimp environment.  If it is, then the number of
  153. active tasks will be greater than zero; if not, the number of tasks will be
  154. zero.
  155.  
  156.  
  157. New Window flags
  158. ----------------
  159.  
  160. bit 10 set ==> don't use colour translation table
  161.  
  162.     If this bit is set, the window colour bytes are to be used directly,
  163.     rather than indirecting via the Wimp colour table (see Wimp.Colours). 
  164.     This feature is intended for use in 256-colour modes, where the range of
  165.     colours available via the Wimp colour table is limited.
  166.  
  167.     Note that any application using this facility must ensure that it takes
  168.     special action in other modes, since the Wimp's automatic
  169.     mode-independence will not apply to such windows.  There is also a
  170.     problem with this: colour 255 in the work area background colour or title
  171.     foreground colour means 'not present', ie. don't paint work area
  172.     background / window has no border.
  173.  
  174. bit 11 set ==> don't open any other windows below this one
  175.  
  176.     This bit is set in the iconbar window (see Wimp.IconBar) and the
  177.     'background window', used when an old-style task is started up (see
  178.     Wimp.Desktop).
  179.  
  180. bit 12 set ==> grab 'hot keys' if the window is open (see Wimp.Text)
  181.  
  182. window areaCBptr =1 ==> use common sprite area
  183.  
  184.     See Wimp.Sprites for further details.
  185.  
  186. window bounds: changed to cover whole screen
  187.  
  188. window min x,y
  189.  
  190.     Wimp_CreateWindow: block!68 = min x,y window size (low 16 bits = min x,
  191.     high 16 bits = min y).  The actual minimum size of the window is the
  192.     maximum of this value and the minimum size as calculated by the Wimp.
  193.  
  194.     Note that this word was reserved on Arthur 1.2 - this means that it
  195.     should be set to 0, but just in case the Wimp actually sets this word to
  196.     zero if the task is an old-style one.
  197.  
  198.  
  199. Service_MouseTrap
  200. -----------------
  201.  
  202. This service call is provided by the Wimp to facilitate the contruction of
  203. utility programs which remember mouse movements by the user, usually in order
  204. to play them back.  The problem is that, in order to save memory, such
  205. programs usually only record the mouse position when one or more of the
  206. buttons change state, or after a specified time delay.  Unfortunately there
  207. are certain user operations which do not require a change in button state,
  208. but whose timing is critical (eg. moving onto a menu arrow or performing a
  209. drag operation).  The problem is that if the program 'misses' the crucial
  210. mouse position, the result of playing back the mouse events recorded is
  211. different from the original effect.
  212.  
  213. So, to get round the problem the Wimp issues a Service_MouseTrap at the
  214. crucial moments (ie. wherever an important mouse position has been acted on,
  215. but which did not require a change in the button state.  Thus a utility which
  216. was recording mouse events would explicitly include the one given by the
  217. Service_MouseTrap (in addition to any which required a change in the button
  218. state).
  219.  
  220. Note that any Wimp applications which also respond to a particular mouse
  221. position, without requiring a change in the button state (in practice this is
  222. rare) should also issue this service.
  223.  
  224. To issue the service call one should perform the following:
  225.  
  226.     SWI OS_ServiceCall
  227.         R0 = mouse x
  228.         R1 = Service_MouseTrap (&52)
  229.         R2 = mouse button state (cf. OS_Mouse) 
  230.         R3 = time of mouse event (cf. OS_ReadMonotonicTime)
  231.         R4 = mouse y
  232.  
  233. Note that R4 = mouse y rather than R1, since that register is already used!
  234.  
  235.  
  236. Special note concerning Service Call handling code
  237. --------------------------------------------------
  238.  
  239. In service call handlers, never corrupt any of R0-R6, unless the issuer of
  240. the service call is explicitly expecting certain registers to change.  For
  241. example, it is OK to set R1=0 in order to claim a service call, but none of
  242. the other registers below R7 should be affected unless they are used to pass
  243. back results.
  244.  
  245. The importance of not corrupting these registers cannot be over-emphasised -
  246. some of the most insidious bugs of all stem from registers not being
  247. preserved over service calls.
  248.  
  249. You have been warned!
  250.  
  251.